終於快走完一半的鐵人賽囉，前幾天初探 Laravel 框架的部分就先暫時結束囉，其實之前所講的部分只是 Laravel 框架的一小部分，但由於是 MVC 架構的骨幹，因此就用了很多篇幅來說明，事實上 Laravel 能做的事情比我們想像還多得多，不知道我在這三十天來不來得及把它透徹的了解 XD。

今天我們來談談 RESTful API 的設計，他是由 Roy Thomas Fielding 博士於 2000 年提出的一種程式碼寫作規範，目的是為了讓不同應用程式在網路中能夠互相傳遞資訊，而在這十年來各種不同的介面或載具，也讓這種寫作風格更加廣泛。

網頁資源（Resources）的操作

RESTful API 的設計是把每一個網頁 URL 作為一項資源，由 HTTP 的協定進行操作，有別一般 API 的操作，能夠以更簡潔的方式完成資源的操作。

如果沒有依據 RESTful API 規範的 URL 設計規範也許會長這樣：

查詢物件 example.com/api/showItem
查詢物件 example.com/api/showItem/1
新增物件 example.com/api/createItem
更新物件 example.com/api/updateItem/1
刪除物件 example.com/api/deleteItem/1

依據 RESTful API 的設計規範：

GET example.com/api/items
GET example.com/api/item/1
POST example.com/api/items
PUT/PATCH example.com/api/item/1
DELETE example.com/api/item/1

兩相對照下，可以發現 RESTful API 的設計更簡單，而且用 HTTP 協定作為存取資源的動作，也能夠幫助前後端在溝通上更順暢，至少在每一次設計 API 的時候都可以有相關的依據。

HTTP 的狀態（Status Code）

我們在 API 間互相傳送資料時，依賴的除了以上的 HTTP method 外，也會依賴 HTTP 的狀態（Status Code），這也符合 RESTful API 設計規範中的 Stateless（無狀態）規範，因此我們所設計的 API 僅需回傳前端所需的資料以及 HTTP Status Code。
下面就列出我比較常用到的 HTTP Status Code

• 200 OK：通用的成功狀態
• 201 Created：新增/修改成功
• 204 No Content：請求成功，但沒有回傳任何內容
• 400 Bad Request：通用的錯誤狀態
• 401 Unauthorized：目前的使用者沒有被授權（系統不知其身份）
• 403 Forbidden：已經登入，但沒有操作的權限（系統已知其身份）
• 404 Not Found：找不到該資源
• 500 Internal Server Error：伺服器錯誤

更詳細的 HTTP 狀態可參考 MDN。

須注意事項

1. API 文件需寫清楚請求及回應格式
   由於 RESTful API 為寫作風格的規範，因此實際專案在跑的時候，可能也會因應需求稍微變動 URL 的寫作方式，以之前處理過的專案來說，GET /api/files/1 是取得某個檔案的名稱，而取得檔案下載網址則是 GET /api/files/1/download，有時候仍須依此進行架構上的調整，並且將這些需求文件化，訂定好每一支 API 的請求以及回應格式，才能夠發展更有彈性的專案架構，因此在公司中我們也很強調清楚的溝通文件。
   但是對於一般來說許多 CRUD 的操作，RESTful API 仍是帶給我們相當便利的設計方法。
2. 不提供轉址服務
   由於 RESTful API 是提倡 Stateful 的設計風格，因此我們的回傳僅需提供給前端需要的資料以及 HTTP 的狀態碼就好，由前端自行依照回傳資料判斷需要做什麼樣的動作。

以上還有很多不同的注意事項，但目前沒有想到太多 XD，先抱歉了，之後再補上來。
明天見囉！